---
title: エージェント
description: Learn more about how to define agents in the OpenAI Agents SDK for JavaScript / TypeScript
---

import { Code } from '@astrojs/starlight/components';
import simpleAgent from '../../../../../../examples/docs/agents/simpleAgent.ts?raw';
import agentWithTools from '../../../../../../examples/docs/agents/agentWithTools.ts?raw';
import agentWithContext from '../../../../../../examples/docs/agents/agentWithContext.ts?raw';
import agentWithAodOutputType from '../../../../../../examples/docs/agents/agentWithAodOutputType.ts?raw';
import agentsAsTools from '../../../../../../examples/docs/agents/agentsAsTools.ts?raw';
import agentWithHandoffs from '../../../../../../examples/docs/agents/agentWithHandoffs.ts?raw';
import agentWithDynamicInstructions from '../../../../../../examples/docs/agents/agentWithDynamicInstructions.ts?raw';
import agentWithLifecycleHooks from '../../../../../../examples/docs/agents/agentWithLifecycleHooks.ts?raw';
import agentCloning from '../../../../../../examples/docs/agents/agentCloning.ts?raw';
import agentForcingToolUse from '../../../../../../examples/docs/agents/agentForcingToolUse.ts?raw';

エージェントは OpenAI Agents SDK の主要な構成要素です。**Agent** は、次の設定が行われた Large Language Model (LLM) です。

- **Instructions** – モデルに _自分が何者か_、_どのように応答すべきか_ を伝えるシステムプロンプト
- **Model** – 使用する OpenAI モデル名と、任意のモデル調整パラメーター
- **Tools** – タスク達成のために LLM が呼び出せる関数や API の一覧

<Code lang="typescript" code={simpleAgent} title="基本的な Agent の定義" />

このページの残りでは、すべての Agent 機能を詳しく説明します。

---

## 基本設定

`Agent` コンストラクターは単一の設定オブジェクトを受け取ります。よく使われるプロパティは次のとおりです。

| Property        | Required | Description                                                                                                                |
| --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `name`          | yes      | 短い人間可読の識別子                                                                                                       |
| `instructions`  | yes      | システムプロンプト（文字列 **または** 関数 – [動的 instructions](#dynamic-instructions) を参照）                           |
| `model`         | no       | モデル名 **または** カスタム [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 実装                             |
| `modelSettings` | no       | 調整パラメーター（temperature、top_p など）。必要なプロパティがトップレベルにない場合は、`providerData` 配下に含められます |
| `tools`         | no       | モデルが呼び出せる [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) インスタンスの配列                         |

<Code lang="typescript" code={agentWithTools} title="ツール付き Agent" />

---

## コンテキスト

エージェントは **コンテキスト型に対してジェネリック** です（例: `Agent<TContext, TOutput>`）。_コンテキスト_ は、あなたが作成して `Runner.run()` に渡す依存性注入オブジェクトです。これはすべてのツール、ガードレール、ハンドオフなどに転送され、状態の保存や共有サービス（データベース接続、ユーザー メタデータ、機能フラグなど）を提供するのに便利です。

<Code
  lang="typescript"
  code={agentWithContext}
  title="コンテキスト付き Agent"
/>

---

## 出力タイプ

既定では、Agent は **プレーンテキスト**（`string`）を返します。モデルに構造化オブジェクトを返させたい場合は、`outputType` プロパティを指定します。SDK は次を受け付けます。

1. [Zod](https://github.com/colinhacks/zod) スキーマ（`z.object({...})`）
2. JSON スキーマ互換の任意のオブジェクト

<Code
  lang="typescript"
  code={agentWithAodOutputType}
  title="Zod による構造化出力"
/>

`outputType` が指定されると、SDK はプレーンテキストではなく自動的に
[structured outputs](https://platform.openai.com/docs/guides/structured-outputs) を使用します。

---

## マルチエージェントの設計パターン

エージェントを組み合わせる方法は多数あります。本番アプリでよく見られるパターンは次の 2 つです。

1. **マネージャー（エージェントをツールとして）** – 中央のエージェントが会話を所有し、ツールとして公開された専門エージェントを呼び出します
2. **ハンドオフ** – 最初のエージェントがユーザーのリクエストを特定したら、会話全体を専門家に委譲します

これらのアプローチは補完的です。マネージャーはガードレールやレート制限を一元的に適用でき、ハンドオフは各エージェントが会話の制御を保持せずに単一タスクに集中できます。

### マネージャー（エージェントをツールとして）

このパターンではマネージャーは決して制御を手放しません。LLM がツールを使い、マネージャーが最終回答を要約します。詳細は [ツール](/openai-agents-js/ja/guides/tools#agents-as-tools) を参照してください。

<Code
  lang="typescript"
  code={agentsAsTools}
  title="ツールとしてのエージェント"
/>

### ハンドオフ

ハンドオフではトリアージ エージェントがリクエストを振り分けますが、一度ハンドオフが行われると、専門エージェントが最終出力を生成するまで会話を所有します。これによりプロンプトが短くなり、各エージェントを個別に考えやすくなります。詳しくは [ハンドオフ](/openai-agents-js/ja/guides/handoffs) を参照してください。

<Code lang="typescript" code={agentWithHandoffs} title="ハンドオフ付き Agent" />

---

## 動的 instructions

`instructions` は文字列の代わりに **関数** にできます。この関数は現在の `RunContext` と Agent インスタンスを受け取り、文字列 _または_ `Promise<string>` を返せます。

<Code
  lang="typescript"
  code={agentWithDynamicInstructions}
  title="動的 instructions を使う Agent"
/>

同期関数と `async` 関数の両方がサポートされています。

---

## ライフサイクルフック

高度なユースケースでは、イベントを購読して Agent のライフサイクルを監視できます。利用可能な項目については、[こちら](https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/lifecycle.ts) に一覧されたエージェント フックのイベント名を参照してください。

<Code
  lang="typescript"
  code={agentWithLifecycleHooks}
  title="ライフサイクルフック付き Agent"
/>

---

## ガードレール

ガードレールにより、ユーザー入力やエージェント出力を検証・変換できます。`inputGuardrails` と `outputGuardrails` 配列で設定します。詳細は
[ガードレール](/openai-agents-js/ja/guides/guardrails) を参照してください。

---

## エージェントのクローン/コピー

既存のエージェントを少しだけ変更したバージョンが必要ですか？`clone()` メソッドを使うと、完全に新しい `Agent` インスタンスが返されます。

<Code lang="typescript" code={agentCloning} title="エージェントのクローン" />

---

## ツール使用の強制

ツールを提供しても、LLM が必ず呼び出すとは限りません。`modelSettings.tool_choice` でツール使用を **強制** できます。

1. `'auto'`（デフォルト）– ツールを使うかどうかは LLM が判断
2. `'required'` – LLM はツールを _必ず_ 呼び出す（どれを使うかは選択可）
3. `'none'` – LLM はツールを呼び出しては **ならない**
4. 特定のツール名（例: `'calculator'`）– LLM はその特定のツールを呼び出す必要がある

<Code
  lang="typescript"
  code={agentForcingToolUse}
  title="ツール使用を強制する"
/>

### 無限ループの防止

ツール呼び出し後、SDK は `tool_choice` を自動的に `'auto'` にリセットします。これにより、モデルがツール呼び出しを繰り返す無限ループに入るのを防ぎます。この動作は `resetToolChoice` フラグ、または `toolUseBehavior` の設定で上書きできます。

- `'run_llm_again'`（デフォルト）– ツール結果を使ってもう一度 LLM を実行
- `'stop_on_first_tool'` – 最初のツール結果を最終回答として扱う
- `{ stopAtToolNames: ['my_tool'] }` – 指定ツールのいずれかが呼ばれた時点で停止
- `(context, toolResults) => ...` – 実行を終了すべきかを返すカスタム関数

```typescript
const agent = new Agent({
  ...,
  toolUseBehavior: 'stop_on_first_tool',
});
```

---

## 次のステップ

- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を学ぶ
- [ツール](/openai-agents-js/ja/guides/tools)、[ガードレール](/openai-agents-js/ja/guides/guardrails)、[モデル](/openai-agents-js/ja/guides/models) を詳しく見る
- サイドバーの **@openai/agents** 配下にある TypeDoc リファレンス全体を参照する
